A.C.E. 1

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 1 / ACE CD 1.iso / files / utils / procal22.dms / in.adf / FAFF.doc < prev

Wrap

Text File | 1991-12-09 | 23.6 KB | 830 lines

FAFF V2.01 (Last editted October 25, 1991) The following is a description of the file format used by Professional Calc V1.0, and Advantage (V1.1 and greater). This file format is also supported by The Gold Disk Office. The Advantage and Office Calc formats are subsets of the Professional Calc format. Note that this description does not carry any kind of warranty, and that the technical support group of Gold Disk will not answer any questions about it (mainly because they are not aquainted with the file format specifications). The specification can change at any time without prior notification; however, we will make sure that we do not obsolete previous FAFF readers and writers (which include our own). Gold Disk is placing this information into the public domain to help third party developpers or users who wish to read or write ProCalc files into their own applications. Structure The concepts behind the structure of FAFF (Fast Advantage File Format) are similiar to those used by Lotus 123 and IFF. The file format is broken into chunks. Each chunk has a one BYTE header number, which describes what kind of chunk it is. Next comes the length bits (which are two BYTEs long), followed by the data. NOTE: the length bits specify the length of the data area only. So one might say that the actual length of a chunk is the value stored in the two length bits, plus three (size of header and the length bits). The structure of FAFF allows the file format to be expanded without obsoleting previous files. It also makes it easier for third parties to look at the file format; they only have to save and load information that is relevant to their application. What follows is a description of the chunks currently used by FAFF. NOTE: the chunks defined are the ONLY legal chunks. People who add in their own chunks may have their files break under future versions of the official Gold Disk FAFF reader program. However, people may submit new chunk definitions to Gold Disk at an address listed at the end of the document, and a chunk number will be supplied to them. When there is a descrepancy between this document, and the actual file format generated by ProCalc, the latter is to be considered correct. Changes in this document: V1.0 : Initial release V1.1 : LinkDisk spreadsheet function number listed. V1.0 of this document incorrectly listed the bits in the Cell Data section. Corrected in this version. V2.0 : Covers new additions to the format in Professional Calc: Pallete Chunk Column Width Chunk Row Height Chunk New Spreadsheet function numbers listed - @() and RexxFun. New Bits in the Data area of a cell listed Password chunk Default Row and Column format chunk Version Chunk Style Tag Chunks Outline chunks Extended Cell chunks Blank Cell Information Miscelaneous typos fixed, and better descriptions of individual chunks added. V2.01 Natural Recalculation bit documented. Typos fixed. Important Notes: All data is stored using 680x0 ordering of the bytes. An FAFF reader for IBM class machines would have to swap the the ordering of the bytes on words. On long words, they would have to swap the ordering of bytes in each of the words, then swap the two words. ProCalc (as well as Office and Advantage) store spreadsheet cells in a sparse matrix. This means that only cells which contain data are kept in memory and on disk. As a result, entire rows and columns could be empty; these empty cells are not stored on disk in any way. Rows and Columns are stored starting from 1; ie Column A is represented as 1, B as 2, etc. All formulas in ProCalc are stored in a tockenize Reverse Polish Notation (RPN) format. This format is described later on in the document. All values are unsigned unless specified otherwise. Chunk Descriptions - End Of File Header: 0 Length: 0 Description: Signals the end of information of a FAFF file. MUST be at the end of the file. - Begin Of File Header: 1 Length: 4 Description : This chunk is used to identify this file as truly being a FAFF file. The data part consists of the magic number 681281268 (in unsigned long integer format). MUST be the first chunk. - Dimensions Header: 2 Length: 8 Description : Bytes 0-1 : Maximum number of rows of the spreadsheet matrix. Must be greater than 0. Bytes 2-3 : Maximum number of columns of the spreadsheet matrix. Must be greater than 0. Bytes 4-5 : Higest row that contains spreadsheet data. Bytes 5-7 : Highest column that contains spreadsheet data. - Column Widths (Only used by Office Calc, Graph and Advantage) Header: 4 Length: 3 Description: Bytes 0-1 are the column number. Byte 2 is the actual width of the column. The only column widths that need to be stored are those that are different from 9. This is the column width in characters (topaz 8 characters to be specific). This chunk is only found in 1.x files of Advantage, and in Office Calc and Office Graph. - Named Cell Header: 8 Length: 20 Description: Bytes 0-1: Row of the named cell. Bytes 2-3: Column of the named cell. Bytes 4-19: NULL terminated string which is the "Name" of this cell. - Named Range Header: 9 Length: 24 Description: Bytes 0-1: Row 1 of the named range. Bytes 2-3: Column 1 of the named range. Bytes 4-5: Row 2 of the named range. Bytes 6-7: Column 2 of the named range. Bytes 8-23: NULL terminated string which is the "Name" of this range. - User Defined Formula Header: 10 Length: Variable Description: Bytes 0-15: Null terminated string which is the name of the formula. Bytes 16- : RPN Stack Structure (described later on). - Version Number (Only used by ProCalc) Header: 15 Length: 2 Description: Bytes 0-1 is the version number of the file format. If the file is a ProCalc V1.0 file (or above) than the version should be set to 4. If the file is intended for previous versions of The Advantage, then omit the chunk all together. This chunk is only used by ProCalc 1.0 and above. - Default formats for a Row or Column (Only used by ProCalc) Header: 16 (for a column) 17 (for a row) Length: 38 Description: ProCalc can set up default formats for a row or a column; this way, the user can pre-format entire rows or columns. Byte 0 : row or column number Bytes 1-27 : Name of the font Bytes 28-29 : Y Size of the font Bytes 30-33 : Cell flags (described later) Bytes 34-35 : New Cell flags (described later) Byte 36 : Color number Byte 37 : Style Tag number - 16 color pallete Header: 21 (Office Calc, Graph and Advantage use a header of 20) Length: 96 Description: Bytes 0-5 are the RGB values of color 0 in the pallete. Bytes 6-11 are the RGB values of color 1 in the pallete. etc. 2 Bytes for each color value. NOTE: Previous versions of the FAFF used a header of 20 for the pallete. However, ProCalc has a different pallete, and depends on certain colors being there. So I, in my infinite wisdom, decided to obsolete the previous pallete definition so old spreadsheets wouldn't mess up the colors. - 256 color pallete (currently ignored) Header: 22 Length: 1536 Description: Bytes 0-5 are the RGB values of color 0 in the pallete. Bytes 6-11 are the RGB values of color 1 in the pallete. etc. - Column Width (Only used by ProCalc) Header: 25 Length: 5 Description: Bytes 0-1 are the column number. Bytes 2-3 are the actual width of the column in pixels. The only column widths that need to be stored are those that are different from 72. The last byte is the flag set for this column. (Those flags will be listed at the end of this document). This chunk is only used by ProCalc V1.0 and above. - Row Heights (Only used by ProCalc) Header: 26 Length: 6 Description: Bytes 0-1 : RowNumber 2-3 : Width 4 : Row flags (same as the column flags) 5 : The size of the largest font descender in the row. - Global Window Information Header: 30 Length: 14 Description: Bytes 0-1: Number of frozen row (if any) Bytes 2-3: Number of frozen col (if any) Bytes 4-7: Unused, but reserved. (can be set to zero) Bytes 8-9: Jump: After return key is hit number of cells to jump. Bytes 10-11: Bitset of window information. Defined later on in document. Byte 12: Boolean value. If 1, then a row is frozen. If 0, then no row is frozen. Byte 13: Boolean value. If 1, then a column is frozen. If 0, then no column is frozen. - Database, and Iterations. Header: 35 Length: 18 Description: Bytes 0-1: Number of spreadsheet iterations. Bytes 2-9: Criteria Range Bytes 10-17 : Database Range - Graph information Header: 40-49 Length: Not applicable. Description: Chunks 40-49 store graphing information for ProCalc. However, at this time, we are not going to be releasing the description of the graphing chunk to the public. At some future point we may, but not right now. These chunks will probably change in the future, so I wouldn't try to hack them out. - Macro File Information Header: 50 Length: 201 Description: The full path name of a macro file to be auto-loaded. Only one macro file can be auto loaded per spreadsheet. - Macro Auto Execute Header: 51 Length: 19 Description: The name of a macro to auto-execute when the spreadsheet finishes loading. Only one macro can be auto-executed per spreadsheet, although ProCalc does allow one macro to call another. NOTE: If there is no pre-loaded macro file, then an error will be generated. - ARexx Auto Execute Header: 52 Length: 401 Description: The full path name of an ARexx file to auto-execute after the spreadsheet finishes loading. May include command line parameters to the ARexx script. The ARexx script will execute AFTER any macro files are loaded and executed; ARexx can then be guaranteed to have some macros in memory if necessary. - Style Tag Chunk (Only used by ProCalc) Header: 60 Length: Variable Description: This chunk stores the style tags. The first section of this chunk stores a null terminated string of variable length which is the name of the font for this style tag. The next two bytes store the size of the font. The next bytes are as follows: Bytes 0-15 : The name of the StyleTag Byte 16 : The ID of the styletag (note, there can be up to 255 unique style tags in a ProCalc file). Byte 17 : The Color of the style tag Bytes 18-21: The Cell BitSet (described later on in the document) Bytes 22-23: The New Cell BitSet (described later on in the document) - Outline Chunk (Only used by ProCalc) Header: 65 Length: 8 Description: Stores the information for an outline. Bytes 0-1: The first row or column of the outline. Bytes 2-3: The last row or column of the outline. Bytes 3-4: The visible row or column from the outline Byte 5 : If set to 1, then this is a row oriented outline. If set to 0, a column oriented outline. Byte 6 : If set to 1, then this outline is on (ie the data is hidden). If set to 0, then the outline is off. - Password (Only used by ProCalc) Header: 80 Length: Variable Description: This chunk store the password (if any) that the user would need to enter on reading a file. The password itself is encrypted; however, to read the spreadsheet, just skip this chunk. The rest of the spreadsheet is not encrypted. - Label Cell information. Header: 100 Length: Variable Description: Place where a cell containing only text is stored. Bytes 0-1: Row of cell. Bytes 2-3: Column of cell. Bytes 4-7: Cell Bitset (described later) Byte 8: Color of cell Cell Note : StringPointer type (described later). Cell note text of the cell. Display : StringPointer type. Actual text of the cell. - Blank Cell information (Only used by ProCalc) Header: 105 Length: Variable Description: Stores cells that only contain formatting information (such as when the user selects a blank range, sets the format of that range to times, then expects any cell entries in that range to be times) Bytes 0-1: Row of cell. Bytes 2-3: Column of cell. Bytes 4-7: Cell Bitset (described later) Byte 8: Color of cell Byte 9: Actual length of Display area (should be zero). Byte 10: Error value of cell. Byte 11: Reserved. CellNote : StringPointer type. - Number Cell information. Header: 110 Length: Variable Description: Place where a cell containing only a number is stored. Bytes 0-1: Row of cell. Bytes 2-3: Column of cell. Bytes 4-7: Cell Bitset (described later) Byte 8: Color of cell Byte 9: Actual length of Display area. Byte 10: Error value of cell. Byte 11: Reserved. Byte 12-19: IEEE number. CellNote : StringPointer type. Display : StringPointer type. Displayed Text. (Can be set to NULL) - Formula Cell information. Header: 120 Length: Variable Description: Place where a formula cell is stored. Bytes 0-1: Row of cell. Bytes 2-3: Column of cell. Bytes 4-7: Cell Bitset (described later) Byte 8: Color of cell Byte 9: Actual length of Display area in characters. Byte 10: Error value of cell. Byte 11: Reserved. Byte 12-19: IEEE number. CellNote : StringPointer type. Display : StringPointer type. Displayed Text. (Can be set to NULL) Formula : RPN Stack. - Extended Cell information. (Only used by ProCalc) Header: 125 Length: Variable Description: New information was added to ProCalc's cell structure since Advantage 1.x. However, instead of obsoleting the previous FAFF cell structures, the new information is stored in a separate chunk. This chunk should come IMMEDIATELY after the chunk that describes the cell. The first section of the chunk holds a NULL terminated string which is the font name of this cell. The next two bytes hold the size of the font. The next bytes are as follows: Bytes 0-1: The new cell bitset (to be described later) Bytes 2 : The style number of this cell. Minimum File: The smallest FAFF file will contain a Begin of File and an End of file chunk. The rest will be assumed to be the data from an "Untitled" ProCalc spreadsheet. Description of FAFF Data Types. - Range Length : 4 Bytes Description: Bytes 0-1: row1 of the range Bytes 2-3: column1 Bytes 4-5: row2 Bytes 6-7: column2 - String Pointer Length : Variable Description: This is a pseudo variable length NULL terminated string. The first BYTE is the length of the remaining data portion of the string. If the first BYTE is 0, then the String Pointer is assumed to be a NULL Pointer. NOTE: This implies that strings have a maximum length of 255 characters. - RPN Stack Length : Variable Description: ProCalc internally stores all its formulas in Reverse Polish Notation. Here is a description of the RPN stack: The first two bytes of an RPN stack store the size of the data following the first two bytes (so the total size of the stack is the value from the first two bytes + 2). Subsequent data has a one byte header, followed by the data for that particular header. End of RPN stack Header: 0 Length: 0 Description: End of RPN formula. IEEE Number Header: 1 Length: Variable. Description: There are three sections. First is a byte, next section is an IEEE double precision real, third is a string which is the ASCII representation of the IEEE. The first byte denotes the length of the string (NOT including the size of the IEEE real) Cell Header: 2 Length: 4 Description: Bytes 0-1: the row of the cell Bytes 2-3: the column of the cell Range Header: 3 Length: 8 Description: Bytes 0-1: row1 of the range Bytes 2-3: column1 of the cell Bytes 4-5: row2 of the range Bytes 6-7: column2 of the cell String Header: 4 Length: Variable Description: Same format as the String Pointer. Operator Header: 5 Length: 2 Description: First BYTE is the operator number. Second BYTE is the number of parameters for the operator. NOTE: The second BYTE is only defined if the function accepts a variable number of parameters (which ProCalc manual describes as a List). List of formulas and their operator numbers will be given later. User Cell Header: 6 Length: Variable Description: String Pointer. Stores the name of a user defined cell. User Range Header: 7 Length: Variable Description: String Pointer. Stores the name of a user defined range. User Formula Header: 8 Length: Variable Description: String Pointer. Stores the name of a user defined formula. Formula Numbers: sin = 1 cos = 2 tan = 3 sinh = 4 cosh = 5 tanh = 6 acos = 7 asin = 8 atan = 9 asinh = 10 acosh = 11 atanh = 12 abs = 13 sign = 14 int = 15 sqrt = 16 log = 17 ln = 18 exp = 19 degtorad = 20 radtodeg = 21 fac = 22 fib = 23 not = 24 row = 25 col = 26 weekday = 27 monthday = 28 month = 29 year = 30 daverage = 31 dcount = 32 dmax = 33 dmin = 34 dstdev = 35 dsum = 36 dvar = 37 rand = 38 e = 39 pi = 40 true = 41 false = 42 hour = 43 now = 44 sec = 45 minutes = 46 today = 47 mod = 48 round = 49 loga = 50 pow = 51 cell = 52 pmt = 53 nper = 54 pv = 55 fv = 56 if = 57 date = 58 time = 59 style = 60 color = 61 range = 62 rate = 63 fvv = 64 npv = 65 irr = 66 hlook = 67 vlook = 68 index = 69 and = 70 or = 71 sum = 72 avg = 73 max = 74 min = 75 count = 76 std = 77 var = 78 xor = 79 choose = 80 iser = 81 isnv = 82 type = 83 lcell = 84 lrange = 85 setcolor = 86 setstyle = 87 sayif = 88 printif = 89 times = 90 pluse = 91 openparen = 92 minus = 93 unary minus = 94 divide = 95 greater = 96 greater or equal = 97 equal = 98 less = 99 less or equal = 100 not equal = 101 power operator = 102 err = 103 na = 104 string = 105 cterm = 106 lrate = 107 sln = 108 term = 109 ddb = 110 syd = 111 isna = 112 isnumber = 113 isstring = 114 n = 115 lcols = 116 lrows = 117 s = 118 clean = 119 code = 120 datevalue = 121 length = 122 lower = 123 upper = 124 proper = 125 timevalue = 126 trim = 127 value = 128 exact = 129 left = 130 repeat = 131 right = 132 find = 133 mid = 134 replace = 135 charf = 136 lhour = 137 lminute = 138 lsecond = 139 linkdisk = 140; getcell = 141; (* The @() operatore *) rexxfun = 142; - Cell Bitset Data (These are the proper values; v1.0 of this document was wrong) Bit 0 : Show number in General format Bit 1 : Scientific Bit 2 : Percent Bit 3 : Currency Bit 4 : Date Bit 5 : Time Bit 6 : Boolean Bit 7 : Commas Bit 8 : If Fixed Decimals, then set. Bit 9 : Left Aligned Bit 10 : Right Aligned Bit 11 : Centered Bit 12 : Underlined Bit 13 : Bold Bit 14 : Italic Bit 15 : Set if a formula cell that returns a string. Bit 16 : Cell Protected (currently unused) Bit 17 : Set if a value cell, or a formula with no errors. Bit 18 : Set if a formula with no errors Bit 19 : Set if cell formula does not reference any cells with greater or equal row values. Bit 20 : Set if cell formula does not reference any cells with greater or equal column values. NOTE: Bit 19 or 20 are cleared if the formula accesses any of the following functions: cell, range, rand, daverage, dcount, dmax, dmin, dstdev, dsum, dvar, hour, today, now, sec, minutes, today, lcell, lrange. Bit 21 : Set if this is a criteria cell Bit 22 : Set if an ARexx script is attached (path stored in the cell note) Bit 23 : Set if a Transcript extended cell note is attached (path stored in the cell note) Bit 24 : Uses Default format (currently unused) Bit 25 : Set if Negative number uses () Bit 26 : reserved for internal use Bit 27 : If a number, or a formula, and the display variable needs to be updated (to be on the safe side, set it when writing the cell). Bits 28-31: Store the number of decimal places after the decimal to calculate to. If Bit 28 set, add 8. If Bit 29 set, add 1. If Bit 30 set, add 2. If Bit 31 set, add 4. - New Cell Bitset Data Bits 0-15 are currently reserved for future use. - Header ByteSet Data Bit 0 : Set if this row/column is to be hidden. Bit 1 : Set if a row is to have a bold header (Currently, the only use of this is if the row is a control point for an outline). Bit 2 : Set if a column is to have an italic header (Currently, the only use of this is if the column is a control point for an outline) Bit 3 : Set if this is the control point for an outline. Bits 4-7 are reserved for future use. - Window Data Bit 0 : Set if to recalculate by rows, else by columns Bit 1 : Set if to recalculate manually, else automatically. Bit 2 : Set if to show the results of formulas, otherwise, displays the formulas. Bit 3 : Set if to use a hollow cell cursor, otherwise filled. Bit 4 : To display a grid, set Bit 5 : If Work Bench is to remain open. Bit 6 : If set, then use narrator device to repeat what user types in. Bit 7 : Set if want to allow ARexx commands. Bit 8 : Cursor jumps up on return Bit 9 : Cursor jumps down on return Bit 10 : Cursor jumps left on return Bit 11 : Cursor jumps right on return Bit 12 : Set if don't want the "Do you REALLY want to do that" requesters. Bit 13 : Set if Control Panel is to be displayed. Bit 14 : Natural recalculation mode is on. Bit 15 : Reserved FAFF Conventions - rows/cols The first row and column in a matrix is 1, NOT zero. So, the cell A1 would be referenced as 1,1; B7 as 7,2. - IEEE Numbers in cells are stored in IEEE double precision format. Get a book on the 68881 or 68882 if you want to see the format of this beast. - Rules Chunks that have a fixed length MUST be of that size. Anything else is considered INVALID. ALL information in chunks must be present, otherwise the FAFF reader will certainly barf. If you can't fill in ALL the data of a chunk, then don't write that chunk. Any unauthorized additions to FAFF is considered INVALID. Micro Systems Software decided that Analyze! would create its own formula numbers for functions that Analyze! supports, but 123 realease 1a did not. As a result their file format can generate giberish when loaded in 123 vesion 2.0 and above. The only information supported by the official Gold Disk FAFF reader is listed here. If a developper wishes to add his/her own chunk, then they should write to Michal Todorovic RE FAFF co Gold Disk PO BOX 789 Streetsville, Mississauga Ontario, Canada L5M-2C2 requesting an official chunk addition. A complete description of the data in the chunk must be provided, along with a reason why this chunk should be officially supported. We do this only to make sure that every FAFF reader and writer are compatible. No chunk definition will be unreasonably refused. This document will be updated periodically as new chunks are added to the FAFF standard, or as errors are found and corrected. I hope that this information will help you understand the FAFF file format. Michal Todorovic Author of The Advantage, Office Calc, Offic Graph and Professional Calc.